<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>XenStore Socket</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5631 2008-08-24 13:01:23Z goodger $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="xenstore-socket">
<h1 class="title">XenStore Socket</h1>

<div class="section" id="introduction">
<h1>Introduction</h1>
<p>XenStore Socket is a lightweithted inter-domain communication (IDC) protocol
for Xen, which is leveraging the XenStore interface only.</p>
</div>
<div class="section" id="news">
<h1>News</h1>
<p>2010-01-18: initial version.</p>
</div>
<div class="section" id="usage">
<h1>Usage</h1>
<ul>
<li><p class="first">Downlad the the source code and compile the demo:</p>
<pre class="literal-block">
# make
</pre>
</li>
<li><p class="first">Start two guests and install the following packages:</p>
<ul class="simple">
<li>xen-devel</li>
<li>xen-tools</li>
</ul>
</li>
<li><p class="first">Make domain 1 a server:</p>
<pre class="literal-block">
# ./server -a guest/xss/server
</pre>
</li>
<li><p class="first">Client side:</p>
<pre class="literal-block">
# dd if=/dev/sda of=/share/tmp/test.img bs=1M count=10
# ./client -d 1 -a guest/xss/server -l guest/xss/client -f /share/tmp/test.img -o /share/tmp/new-test.img
</pre>
<p>The above commands will transfer <cite>/share/tmp/test.img</cite> to domain 1 and
rename it to <cite>/share/tmp/new-test.img</cite>.</p>
</li>
</ul>
</div>
<div class="section" id="performance">
<h1>Performance</h1>
<p>On a common computer (2G Memory, Intel dual core CPU at 2.33GHz), file
transfer can reach 2MB/s.</p>
</div>
<div class="section" id="download">
<h1>Download</h1>
<p>The source code repository is managed by Mercurial (hg) and can be cloned by:</p>
<blockquote>
$ hg clone <a class="reference external" href="https://xenstore-socket.googlecode.com/hg/">https://xenstore-socket.googlecode.com/hg/</a> xenstore-socket</blockquote>
</div>
<div class="section" id="known-issues">
<h1>Known issues</h1>
<ul class="simple">
<li>The XenStore watching mechanism is not reliable in domU. The testing program
<cite>test-xs-watch</cite> will hang on domU (EL5.4 X86 PVM), but success on dom0.</li>
<li>When transfer file between domU (EL5.4 X86 PVM) and dom0, it
sometimes hang on random point.</li>
</ul>
<p>I'm not sure it's a usage issue, or the domU xenbus implement issue.</p>
<p>Before these issues are resolved, there's no further development is needed.</p>
</div>
<div class="section" id="design">
<h1>Design</h1>
<ul>
<li><p class="first">The API is most influenced by the Berkeley sockets for User Datagram Protocol (UDP).</p>
</li>
<li><p class="first">Data structure:</p>
<pre class="literal-block">
struct xs_sock {
    struct xs_handle *xsh;
    unsigned int domid;
    char addr[ENTRYSIZE];
};
</pre>
<p>The URI of the socket is: <cite>&lt;domid&gt;:&lt;addr&gt;</cite>.</p>
</li>
<li><p class="first">Methods:</p>
<pre class="literal-block">
struct xs_sock *xss_open(char *addr);

int xss_close(struct xs_sock *sock);

ssize_t xss_sendto(struct xs_sock *sock, void *buf, size_t len, struct xs_sock *dest_sock);

ssize_t xss_recvfrom(struct xs_sock *sock, void *buf, size_t len, struct xs_sock *src_sock);
</pre>
</li>
<li><p class="first">A typical inter-domain commnunication (IDC) process:</p>
<ul>
<li><p class="first">dom1 open socket (<cite>xss_open</cite>):</p>
<ul>
<li><p class="first">Create xenstore keys:</p>
<pre class="literal-block">
/local/domain/1/xss/0/evtchn
/local/domain/1/xss/0/buffer
</pre>
</li>
<li><p class="first">Watch on <cite>/local/domain/1/xss/0/evtchn</cite>.</p>
</li>
</ul>
</li>
<li><p class="first">dom1 start receiving (<cite>xss_recvfrom</cite>):</p>
<ul class="simple">
<li>dom1 hang on <cite>read_watch</cite>.</li>
</ul>
</li>
<li><p class="first">dom2 open socket (<cite>xss_open</cite>):</p>
<ul>
<li><p class="first">Create xenstore keys:</p>
<pre class="literal-block">
/local/domain/2/xss/0/evtchn
/local/domain/2/xss/0/buffer
</pre>
</li>
<li><p class="first">Watch on <cite>/local/domain/2/xss/0/evtchn</cite>.</p>
</li>
</ul>
</li>
<li><p class="first">dom2 start sending data to dom1 (<cite>xss_sendto</cite>):</p>
<ul>
<li><p class="first">dom2 write data to:</p>
<pre class="literal-block">
/local/domain/1/xss/0/buffer
</pre>
</li>
<li><p class="first">dom2 write it's URI (<cite>2:/xss/0</cite>) to:</p>
<pre class="literal-block">
/local/domain/1/xss/0/evtchn
</pre>
</li>
<li><p class="first">dom2 wait for response from dom1 (read_watch).</p>
</li>
</ul>
</li>
<li><p class="first">dom1 read_watch returns, and handles contents in:</p>
<pre class="literal-block">
/local/domain/1/xss/0/evtchn
/local/domain/1/xss/0/buffer
</pre>
<p>dom1 will know who send the contents in <cite>buffer</cite> by parsing the URI in
<cite>evtchn</cite>.</p>
<p>After handled the data, dom1 will give a response to dom2 by writing its
URI to dom2's evtchn:</p>
<pre class="literal-block">
/local/domain/2/xss/0/evtchn
</pre>
</li>
<li><p class="first">dom2 gets the response, and one communication finished.</p>
</li>
<li><p class="first">Finally dom1 and dom2 close their sockets (<cite>xss_close</cite>).</p>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="faq">
<h1>FAQ</h1>
<ul class="simple">
<li>Why reinventing the wheel rather than improving <a class="reference external" href="http://sourceforge.net/projects/xway/">Xway</a> or <a class="reference external" href="http://sourceforge.net/projects/xvmsocket/">Xen Socket</a>?<ul>
<li>XenStore socket is simpler and easier to port to different platforms.</li>
<li>XenStore socket is not intended for high performance.</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="reference">
<h1>Reference</h1>
<ul class="simple">
<li><a class="reference external" href="http://sourceforge.net/projects/xway/">Xway</a>.</li>
<li><a class="reference external" href="http://sourceforge.net/projects/xvmsocket/">Xen Socket</a>.</li>
<li><a class="reference external" href="http://osnet.cs.binghamton.edu/projects/xenloop.html">XenLoop</a>.</li>
<li><a class="reference external" href="http://www.computer.org/portal/web/csdl/doi/10.1109/CIT.2009.50">SChannel</a>.</li>
<li><a class="reference external" href="http://www.vmware.com/support/developer/vmci-sdk/">VMCI Sockets</a>.</li>
<li><a class="reference external" href="http://zhigang.org/wiki/XenStore">XenStore</a>.</li>
</ul>
</div>
<div class="section" id="contacts">
<h1>Contacts</h1>
<p>Zhigang Wang &lt;<a class="reference external" href="mailto:w1z2g3&#64;gmail.com">w1z2g3&#64;gmail.com</a>&gt;</p>
</div>
</div>
</body>
</html>
